---
title: 'Per-customer configuration'
sidebarTitle: 'Per-customer config'
description: 'How to add per-customer configuration to your Nango integrations'
---

Nango has a flexible approach to letting you customize integrations per customer:
- Store customer-specific data in the **connection metadata**
- Access customer-specific metadata in integration [functions](/guides/platform/functions) to customize the integration behavior

# Store customer-specific data

Nango lets you store arbitrary metadata on individual connections. This is useful for customizing an integration's behavior per end-customer.

Connection metadata can be set, updated, and retrieved with the SDK ([reference](/reference/sdks/node#set-connection-metadata)) and API ([reference](/reference/api/connection/set-metadata)). It can also be retrieved on the Nango UI, in the **Connections** tab > **Select Connection** > **Authorization** tab:

**Set connection metadata**

<Tabs>
<Tab title="Node">

```typescript
await nango.setMetadata(
    '<INTEGRATION-ID>', 
    '<CONNECTION-ID>', 
    { any_key: 'Any Value' }
);
```
</Tab>

<Tab title="REST API">

```bash
curl --request POST \
  --url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Provider-Config-Key: <INTEGRATION-ID>' \
  --data '{ "any_key": "Any Value" }'
```

</Tab>

</Tabs>

**Update connection metadata**

<Tabs>
<Tab title="Node">

```typescript
await nango.updateMetadata(
    '<INTEGRATION-ID>', 
    '<CONNECTION-ID>', 
    { any_key: 'Any Value' }
);
```
</Tab>

<Tab title="REST API">

```bash
curl --request PATCH \
  --url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Provider-Config-Key: <INTEGRATION-ID>' \
  --data '{ "any-key": "Any Value" }'
```

</Tab>

</Tabs>

**Get connection metadata**

<Tabs>
<Tab title="Node">

```typescript
await nango.getMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>');
```
</Tab>

<Tab title="REST API">

```bash

curl --request GET \
  --url 'https://api.nango.dev/connection/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
  --header 'Authorization: Bearer <TOKEN>'

```

</Tab>

</Tabs>

<Warning>
When accessing metadata from within a sync using `nango.getMetadata()`, the metadata is cached for up to 60 seconds. Changes made to metadata while a sync is running may not be visible until the cache expires.

The next execution of the sync will always have access to the latest metadata.
</Warning>

# Use custom field mappings

Field mappings are necessary when a [sync](/guides/use-cases/syncs) needs to access information stored in external custom fields. Nango provides dedicated tools to support complex field mappings.

### Prompt your customers for field mappings

In your app:
- Fetch the list of custom fields available from the external API using an [action](/guides/use-cases/actions)
- Display the full list of external custom fields to the user
- Prompt the user to associate the data you need to collect to the relevant external custom fields

The output of this step should be a field mapping object such as: 
```json
 {
    "internal_field_1": "custom_field_1",
    ...
 }
```

### Store field mappings in the connection metadata

Update the relevant connection's metadata with the obtained field mapping object using the SDK ([reference](/reference/sdks/node#set-connection-metadata)) or API ([reference](/reference/api/connection/set-metadata)): 
<Tabs>
<Tab title="Node">

```typescript
await nango.setMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>', { internal_field_1: 'custom_field_1' });
```
</Tab>

<Tab title="REST API">

```bash
curl --request PATCH \
  --url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Provider-Config-Key: <INTEGRATION-ID>' \
  --data '{ "internal_field_1": "custom_field_1" }'
```

</Tab>

</Tabs>

### Start the sync for each connection

Start the **sync** schedule programmatically for this connection with the SDK ([reference](/reference/sdks/node#start-schedule-for-syncs)) or API ([reference](/reference/api/sync/start)): 

<Tabs>
<Tab title="Node">
```typescript
await nango.startSync('<INTEGRATION-ID>', ['hubspot-sync'], '<CONNECTION-ID>');
```
</Tab>
<Tab title="REST API">
```bash
curl --request POST \
  --url https://api.nango.dev/sync/start \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "connection_id": "<CONNECTION-ID>",
  "provider_config_key": "<INTEGRATION-ID>",
  "syncs": [ "hubspot-sync" ]
}'
```
</Tab>
</Tabs>

The sync's internal logic will use the field mappings to fetch the relevant data from custom fields.

<Tip>
    **Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>